Skip to content

Comments

[homekit.binding] New HomeKit client binding#19340

Merged
lsiepel merged 192 commits intoopenhab:mainfrom
andrewfg:homekit-client
Dec 13, 2025
Merged

[homekit.binding] New HomeKit client binding#19340
lsiepel merged 192 commits intoopenhab:mainfrom
andrewfg:homekit-client

Conversation

@andrewfg
Copy link
Contributor

@andrewfg andrewfg commented Sep 16, 2025 •
edited
Loading

Resolves #14094

There is an existing HomeKit system integration addon which allows exporting OH Items into the HomeKit eco- system.
This is a new HomeKit client binding addon which allows importing OH Things and Channels from the HomeKit eco- system.

There are three types of Things supported:

  • accessory: This integrates a single HomeKit accessory, which has its own LAN connection.
    Its services appear as channel groups, and their respective characteristics appear as channels.
  • bridged-accessory: This integrates a single HomeKit accessory, which does NOT have its own LAN connection.
    It has the same functionality as an accessory, except that its communication is done via a bridge (see below).
  • bridge: This integrates a HomeKit bridge accessory, which has its own LAN connection.
    It does not have any own channels.
    Instead it contains multiple bridged-accessory Things (see above).

Things of type bridge and accessory both communicate directly with their HomeKit device over the LAN. Whereas bridged-accessory Things communicate via their respective bridge Thing.

The JAR files for testing purposes are here:

See Apple HomeKit Specification.pdf for reference.

Notes:

  1. This binding uses a clone of the code in my Light State Model PR here for the time being. Note that once that PR will have been merged, the clone in this binding can be deleted and instead linked to use that library.
  2. I did make contact with @kgoderis since he has also a huge HomeKit project that is also work-in-progress. However he told me that he has no time to make further progress on his work. So I decided to make a clean re-start from scratch.

Signed-off-by: Andrew Fiddian-Green software@whitebear.ch

Todos (all done)
  • State options for enums
  • Convert 2 step enums to Switch/Contact
  • Adopt discovery PR from @jlaur
  • Rollershutter instead of Dimmer, with up/down
  • Add 'aid' to make thing labels unique
  • Add intricate test cases for Velux Json dump
  • Check arc degree usage
  • Implement light state machine (see State machine to model lights in Thing handlers openhab-core#4995)
  • Add code to reconnect if socket gets dropped
  • Rollershutter add stop (position hold) override
  • Implement button trigger channels
  • i18n on thing status messages
  • Support event subscription and notification
  • Fix the disposition of On/Off derived from B part of OH HSB command
  • i18n on channel labels
  • i18n on state option labels
  • Implement thing action for pairing
  • Implement addon suggestion finder
  • Unique channel type and group type ids
Issues that will NOT be addressed
  • Coalesce target and current channels
  • Identify device

@andrewfg
initial contribution
ce7a3e1 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
work in progress
72bb54a 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
work in progress
f20fc81 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
work in progress
62aaa90 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
Merge branch 'openhab:main' into homekit-client
1cc5a0b
@andrewfg
work in progress
1a1824a 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
Merge branch 'homekit-client' of https://github.com/andrewfg/openhab-…
4cac1c8 
…addons into homekit-client
@andrewfg
work in progress
f11ec7f 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
work in progress
4417971 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
work in progress
6217919 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
fix wrong exception type
46a7904 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
work in progress
9de2d04 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
work in progress
84ff44a 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
work in progress
6151a88 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
work in progress
81706c8 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
work in progress
0477c23 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
Merge remote-tracking branch 'upstream/main' into homekit-client
3ea7db7
@andrewfg
work in progress
1358bc2 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg andrewfg self-assigned this Sep 16, 2025
@andrewfg andrewfg requested a review from a team as a code owner September 16, 2025 18:12
@andrewfg andrewfg added new binding If someone has started to work on a binding. For a new binding PR. work in progress A PR that is not yet ready to be merged labels Sep 16, 2025
@andrewfg

This comment was marked as outdated.

Sign in to view
@lsiepel lsiepel marked this pull request as draft September 16, 2025 18:24
@lsiepel

This comment was marked as outdated.

Sign in to view
@lsiepel lsiepel requested a review from Copilot September 16, 2025 18:27
@andrewfg
line endings
22878c2 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

This comment was marked as outdated.

Sign in to view

@andrewfg
Copy link
Contributor Author

andrewfg commented Dec 12, 2025

@ThomasM102 I think you successfully integrated your own Hue bridge via this binding? That actually was a surprise for me since my own Hue bridges (a white v2 and a black v3) did not appear in my Inbox.

However on December 8th Philips/Signify announced a new firmware roll out and miracolo miracoli both of them appeared -- for a very short time -- in my Inbox :) However unfortunately before I could try to pair with them, they both equally suddenly disappeared from the Inbox again :(

So I am wondering if you used some special "magic" to discover your bridges and/or to pair them?

@ThomasM102
Copy link

ThomasM102 commented Dec 12, 2025

Yes, really, this takes magic (and maybe an iPhone too; I haven't tested it with Android):

  1. Delete any existing pairings in the Hue app.
  2. Start the HomeKit pairing process in the Hue app, but only until the app says: "3 LEDs are now lit." Don't go any further, otherwise it will pair with your local HomeKit.
  3. Press the pairing button on the Hue device. It should now be blinking.
  4. Then start the scan with your binding.

This is how the discovery process worked for me with your binding.

@andrewfg
tweak equipment tag code
b1a951f 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
Copy link
Contributor Author

andrewfg commented Dec 12, 2025

maybe an iPhone too; I haven't tested it with Android

Aha. The Android app doesnt even mention an Apple Home option. But fortunately I do also have an iPad so I will try that..

Is it the case that the bridge only appears in the mDNS discovery after your step 3 in the app?

Also which of the two Thing Actions in the binding did you use?

@ThomasM102
Copy link

ThomasM102 commented Dec 12, 2025

Is it the case that the bridge only appears in the mDNS discovery after your step 3 in the app?

Yes, it looks like multicasting needs to be activated through the app and the hardware first. It took a lot of trial and error to find this solution. There might be an easier way, but this is how it worked for me.
If you delete the pairing and the bridge, you then have a few minutes to perform a new scan/pairing. Only after a certain amount of time does it need to be reactivated via the app and the button. At least that's been my experience.

Also which of the two Thing Actions in the binding did you use?

I just tested both again. Everything works. Pairing works without the "With External Authentication" switch.

jlaur
jlaur requested changes Dec 12, 2025
View reviewed changes
Copy link
Contributor

@jlaur jlaur left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had a look at your latest commits, and they LGTM. The README needs a small update after that. I had a quick look at all files changed within the last week or so, and added two ultra-minor comments.

When the README is updated, we can merge. I expect to do that sometime tomorrow (and if you are not available before then, I'll just commit that README update).

Thanks for the massive effort put into this. This is going to be a major new feature in 5.1.

@jlaur

This comment was marked as resolved.

Sign in to view
andrewfg and others added 3 commits December 12, 2025 23:08
@andrewfg @jlaur
Update bundles/org.openhab.binding.homekit/README.md
a9d0cc2 
Co-authored-by: Jacob Laursen <jacob-github@vindvejr.dk>
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg @jlaur
Update bundles/org.openhab.binding.homekit/src/main/java/org/openhab/…
8232057 
…binding/homekit/internal/handler/HomekitBridgeHandler.java

Co-authored-by: Jacob Laursen <jacob-github@vindvejr.dk>
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg @jlaur
Update bundles/org.openhab.binding.homekit/src/main/java/org/openhab/…
178ee86 
…binding/homekit/internal/enums/AccessoryCategory.java

Co-authored-by: Jacob Laursen <jacob-github@vindvejr.dk>
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg andrewfg requested a review from jlaur December 12, 2025 23:12
jlaur
jlaur approved these changes Dec 12, 2025
View reviewed changes
Copy link
Contributor

@jlaur jlaur left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@lsiepel
Copy link
Contributor

lsiepel commented Dec 13, 2025

@andrewfg if you can fix the conflicts due to the merge of other new bindings, we can finally merge this awesome contribution.

@andrewfg
Merge branch 'main' into homekit-client
7450b0b 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
fix bad github merge suggestion
7b6b1d2 
Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
@andrewfg
Copy link
Contributor Author

andrewfg commented Dec 13, 2025

fix the conflicts due to the merge of other new bindings

@lsiepel done.

lsiepel
lsiepel approved these changes Dec 13, 2025
View reviewed changes
Copy link
Contributor

@lsiepel lsiepel left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As @jlaur did the extensive review and Approved and the conflict is now resolved and reviewed LGTM.
Next step is to add the binding's logo.

@lsiepel lsiepel merged commit b72a292 into openhab:main Dec 13, 2025
2 checks passed
@lsiepel lsiepel added this to the 5.1 milestone Dec 13, 2025
@lsiepel
Copy link
Contributor

lsiepel commented Dec 13, 2025

Thanks for all the hard work on this binding @andrewfg !

@andrewfg
Copy link
Contributor Author

andrewfg commented Dec 13, 2025

Next step is to add the binding's logo.

There is already a Homekit logo for org.openhab.io.homekit and we (myself and @jlaur) think that org.openhab.binding.homekit will therefore pull in that same logo. But @lsiepel can you please check it?

@lsiepel
Copy link
Contributor

lsiepel commented Dec 13, 2025

Next step is to add the binding's logo.

There is already a Homekit logo for org.openhab.io.homekit and we (myself and @jlaur) think that org.openhab.binding.homekit will therefore pull in that same logo. But @lsiepel can you please check it?

I think you two are right. Let's see after the snapshot build. We can always add the logo th enext week during feature freeze

@jlaur
Copy link
Contributor

jlaur commented Dec 13, 2025

I think you two are right. Let's see after the snapshot build. We can always add the logo th enext week during feature freeze

We can also replace it with a new SVG logo. It seems the logo changed over the years - is this the latest logo?

If the logo will automatically be picked up as expected, we have a small issue further down the road: If we will ever have two bindings with the same name in different categories (binding/persistence/io ec.), it seems it's currently not possible to use fully qualified names and thus use different logos (if desired). Maybe fully or partially qualified names are already supported, I haven't checked, but there are no examples to prove it. 😉

@andrewfg

This comment was marked as resolved.

Sign in to view
@andrewfg
Copy link
Contributor Author

andrewfg commented Dec 13, 2025 •
edited
Loading

Do you want me to make a PR replacing the old homekit.png with the new homekit.svg ?

EDIT done here

@andrewfg andrewfg deleted the homekit-client branch December 14, 2025 11:55
@jlaur
Copy link
Contributor

jlaur commented Dec 14, 2025

Let's see after the snapshot build.

It works: https://next.openhab.org/addons/bindings/homekit/

@andrewfg
Copy link
Contributor Author

andrewfg commented Dec 14, 2025

But we still need to merge openhab/openhab-docs#2608

@andrewfg andrewfg changed the title [homekit] New HomeKit client binding [binding.homekit] New HomeKit client binding Feb 11, 2026
@andrewfg andrewfg changed the title [binding.homekit] New HomeKit client binding [homekit.binding] New HomeKit client binding Feb 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@lsiepel lsiepel lsiepel approved these changes

@jlaur jlaur jlaur approved these changes

@kgoderis kgoderis Awaiting requested review from kgoderis

@ccutrer ccutrer Awaiting requested review from ccutrer

@andylintner andylintner Awaiting requested review from andylintner

@yfre yfre Awaiting requested review from yfre

+1 more reviewer

@ThomasM102 ThomasM102 ThomasM102 approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

@andrewfg andrewfg

Labels

new binding If someone has started to work on a binding. For a new binding PR.

Projects

None yet

Milestone

5.1

Development

Successfully merging this pull request may close these issues.

[homekit] HomeKit Binding

10 participants

@andrewfg @lsiepel @jimtng @ccutrer @jlaur @ThomasM102 @openhab-bot @ErikDB87 @fwPunsher @kaikreuzer